ODShape

Inside Macintosh: OpenDoc Class Reference /: Part 1 - Classes and Methods

ODShape

Superclasses
ODRefCntObject --> ODObject
Subclasses
none

An object of the ODShape class represents a geometric shape that OpenDoc uses to manage the display of parts.

Description
Shape objects encapsulate geometric shapes. The simplest shape is an empty shape, which occupies no area.
Your part creates an empty shape by calling the CreateShape method (page 316) of a frame, the CreateShape method (page 241) of a facet, or the NewShape method (page 645) of an existing shape. Your part can create a copy of an existing shape by calling that shape's Copy method (page 634).
Frames and facets use the following kinds of shape objects for frame negotiation, clipping, and hit-testing.

A frame shape defines the area that the containing part delegates to an embedded part's display frame.
A clip shape defines the area of a facet in which drawing can occur; it is the area not obscured by overlapping content of the containing part.
A used shape defines the area of an embedded part's frame that has actual content to display; the containing part is free to display its own content within the embedded frame, but it must remain outside the used shape area.
An active shape defines the area of a facet within which the embedded part responds to mouse events.

For more information about frame shapes and used shapes, see the ODFrame class description (page 294); for information about clip shapes and active shapes, see the ODFacet class description (page 219). For more information on the graphics systems available on the Mac OS platform, see Inside Macintosh: Imaging with QuickDraw and Inside Macintosh: QuickDraw GX Graphics.

Geometric Representation
The geometric representation of a shape is a description of its outline as a rectangle or polygon (or possibly as a series of curves if an advanced rendering system such as QuickDraw GX is available). A shape might not have a geometric representation if it is represented internally by a platform-specific data structure. For example, on the Mac OS platform, a shape may be represented by a QuickDraw region, which consists of a set of pixels rather than a polygonal outline.
A geometric (polygonal) representation of a shape can always be converted into a platform-specific representation. However, if a shape has no geometric representation, it cannot necessarily generate one. (On the Mac OS platform, a region-based shape can in fact be converted back to a polygon, but the conversion usually results in loss of accuracy and ugly stair-step effects on diagonal edges.)
The distinction is important because certain methods in the ODShape class require the shape to have a geometric (polygonal) representation. For example, for the Transform method (page 654) to apply a complex transformation such as a rotation, scale, or skew to a shape, the shape must have a geometric representation.
In addition, to ensure cross-platform compatibility, shapes that are stored persistently in documents and written to storage unit values (such as frame shapes) must be stored as polygons. A shape with no geometric representation cannot be stored in a document that could be moved to another platform.

Geometry Mode
The geometry mode of a shape object specifies whether the shape is required to maintain its geometric (polygonal) representation. The geometry mode has three possible values:

Preserve geometry (kODPreserveGeometry) is the default value and indicates that the shape must maintain its polygonal representation for as long as possible. A shape's polygonal representation is lost if the shape is combined with (that is, unioned with, subtracted from, or intersected with) a shape that does not have a polygonal representation. The shape's polygonal representation is replaced by the area that results from combining the two shapes.
Lose geometry (kODLoseGeometry) indicates that the shape does not need to use a polygon to describe its geometric representation. The polygonal representation can be discarded in order to optimize speed, but at the expense of accuracy and persistent storage capability. For example, on the Mac OS platform, a shape's geometry can be represented by a QuickDraw region (rather than a polygon) to take advantage of the built-in region operators of QuickDraw, which are much faster than the polygon clipper in OpenDoc. This mode is often used for a frame's used shape, which is nonpersistent and onscreen only.
Needs geometry (kODNeedsGeometry) indicates that the shape must always maintain its polygonal representation. The shape cannot be unioned with, subtracted from, or intersected with a shape that does not have polygonal representation. If you attempt to do so, the shape raises an exception and does not modify its geometric representation.

Geometric Operations
Shape objects support geometric operations such as union, intersection, and difference. A platform-specific shape-manipulation engine may be used to perform these operations. As a consequence, the results of certain operations, such as test for equality, difference, union, and intersection, may vary slightly from platform to platform; these cross-platform differences should be apparent only at the pixel level.

Methods
This section presents summary descriptions of the ODShape methods grouped according to purpose, followed by detailed descriptions in alphabetical order. Methods marked [M] are specific to the Mac OS platform.
Creating Shapes

NewShape
Creates a new empty shape object.
Copy
Creates a new shape object that is a copy of this shape.
Manipulating Shape Geometry

ReadShape
Reads shape data from the specified storage unit into this shape.
WriteShape
Writes this shape to the specified storage unit.
CopyFrom
Modifies this shape to make it equivalent to the specified source shape.
Reset
Replaces this shape's geometric representation with an empty area.
CopyPolygon
Returns a copy of this shape's geometric representation, expressed as a polygon.
SetPolygon
Modifies this shape to make it equivalent to the specified polygon.
GetBoundingBox
Returns, in the specified structure, the smallest rectangle that surrounds this shape.
SetRectangle
Modifies this shape to make it equivalent to the specified rectangle.
GetPlatformShape
Returns a graphics-system-specific data structure representing this shape.
SetPlatformShape
Modifies this shape to make it equivalent to the specified graphics-system-specific shape.
GetQDRegion [M]
Returns an approximation of this shape in the form of a read-only QuickDraw region.
CopyQDRegion [M]
Returns an approximation of this shape in the form of a new, modifiable QuickDraw region.
SetQDRegion [M]
Modifies this shape to make it equivalent to the specified QuickDraw region.
GetGXShape [M]
Returns the geometric representation of this shape, expressed as a QuickDraw GX shape.
SetGXShape [M]
Modifies this shape to make it equivalent to the specified QuickDraw GX shape.
Testing the Shape

IsEmpty
Returns a Boolean value that indicates whether this shape is empty (occupies no area).
IsRectangular
Returns a Boolean value that indicates whether this shape can be described by a rectangle.
HasGeometry
Returns a Boolean value that specifies whether the geometric representation of this shape can be described by a polygon.
IsSameAs
Returns a Boolean value that indicates whether this shape is identical to the specified shape.
ContainsPoint
Returns a Boolean value that indicates whether the specified point is within the area of this shape.
Manipulating Geometry Mode

GetGeometryMode
Returns the current geometry mode of this shape.
SetGeometryMode
Sets the geometry mode of this shape.
Performing Geometric Operations

Intersect
Modifies this shape by intersecting it with the specified shape.
Outset
Modifies this shape by moving its boundary outwards--away from its interior--by the specified distance.
Subtract
Modifies this shape by subtracting the specified shape from it.
Union
Modifies this shape to be the union of this shape and the specified shape.
Transform
Modifies this shape by applying the specified transform to it.
InverseTransform
Modifies this shape by applying the inverse of the specified transform to it.

Methods
ContainsPoint
Copy
CopyFrom
CopyPolygon
CopyQDRegion
GetBoundingBox
GetGeometryMode
GetGXShape
GetPlatformShape
GetQDRegion
HasGeometry
Intersect
InverseTransform
IsEmpty
IsRectangular
IsSameAs
NewShape
Outset
ReadShape
Reset
SetGeometryMode
SetGXShape
SetPlatformShape
SetPloygon
SetQDRegion
SetRectangle
Subtract
Transform
Union
WriteShape